Cargar Carpeta Tributaria

Este endpoint permite cargar una Carpeta Tributaria (PDF) asociada a un RUT e iniciar su procesamiento. La carga es asíncrona: la respuesta entrega un identificador de seguimiento (carpetaTributariaId) y el resultado estructurado se obtiene posteriormente.

• El archivo debe ser un PDF válido de la Carpeta Tributaria emitido por el SII, con un tamaño máximo de 35 MB.
• El PDF se valida antes de cargar el perfil, de modo que un PDF inválido no genera una carga de perfil.
• Si el RUT no está activo en tu cuenta de Sheriff, se carga automáticamente al subir la carpeta (no es necesario cargarlo antes).

Detalle de API

Request

• URL: /helper/carpetaTributaria/{rut}
• Método: POST
• Content-Type: multipart/form-data

Parámetros

• rut (requerido, path): El RUT del contribuyente dueño de la carpeta. Formato del rut "12345678-9".
• file (requerido, body): Archivo PDF de la Carpeta Tributaria, enviado como multipart/form-data. Tamaño máximo 35 MB.

Ejemplo request con curl

curl -X 'POST' \
  'https://prod.api.thesheriff.cl/api/clients/v2/helper/carpetaTributaria/12345678-9' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9EjemploDeToken123' \
  -H 'x-client-identifier: SheriffSecureClient-v1' \
  -F 'file=@carpeta_tributaria.pdf'

Response

Success

• Status code: 200

• Example response body:

  {
    "success": true,
    "data": {
      "carpetaTributariaId": 12345
    }
  }

  A continuación se describen los campos devueltos en la respuesta JSON.

  Campo	Tipo	Descripción
  success	bool	Indica si la operación fue exitosa.
  data	object	Objeto con el identificador de la carga registrada.

  Campos dentro de data:

  Campo	Tipo	Descripción
  carpetaTributariaId	number	Identificador de la carga. Úsalo para hacer seguimiento del procesamiento y obtener el resultado.

  Entrega del resultado

  La carga inicia el procesamiento de la Carpeta Tributaria de forma asíncrona: el PDF se almacena y se procesa en segundo plano. Una vez finalizado el procesamiento, puedes obtener el resultado de dos formas:

  • Push (recomendado): Recibe el resultado automáticamente en tu URL mediante el webhook processTaxFolder. Requiere tener un webhook activo configurado en la plataforma (ver Configurar Webhooks). El webhook solo se dispara para cargas realizadas por la API.
  • Pull: Consulta periódicamente Estado Carpeta Tributaria hasta obtener SUCCEEDED o FAILED, y luego obtén los datos con Resultado Carpeta Tributaria.
  Webhook idempotente

  El payload del webhook es idéntico al que entrega el endpoint de resultado, y su envío es idempotente: los reintentos de verificación o el timeout de procesamiento no generan webhooks duplicados ni contradictorios sobre una carpeta ya entregada. Si el procesamiento falla, el webhook entrega el error correspondiente.

  Errores

  Para este endpoint, un 400 indica que falta el archivo (campo file) o que el PDF es inválido / no se pudo leer.

  400 - Solicitud inválida

  {
    "success": false,
    "code": 400,
    "error": "Solicitud inválida"
  }

  401 - No autorizado

  {
    "success": false,
    "code": 401,
    "error": "No autorizado"
  }

  403 - No tienes permiso para acceder a este recurso

  {
    "success": false,
    "code": 403,
    "error": "No tienes permiso para acceder a este recurso"
  }

  404 - Recurso no encontrado

  {
    "success": false,
    "code": 404,
    "error": "Recurso no encontrado"
  }

  408 - Tiempo de espera agotado

  {
    "success": false,
    "code": 408,
    "error": "Tiempo de espera agotado"
  }

  429 - Demasiadas solicitudes

  {
    "success": false,
    "code": 429,
    "error": "Demasiadas solicitudes"
  }

  500 - Error interno del servidor

  {
    "success": false,
    "code": 500,
    "error": "Error interno del servidor"
  }